<!DOCTYPE html>
<html lang="en">
<head>
  <title>The Apache Shiro Auth provider implementation - Vert.x</title>
  <meta charset="utf-8">
  <meta http-equiv="X-UA-Compatible" content="IE=edge">
  <meta content="width=device-width, initial-scale=1.0" name="viewport">
  <meta content="Vert.x is a tool-kit for building reactive applications on the JVM." name="description">
  <link href="http://vertx.io/stylesheets/docs.css" media="screen" rel="stylesheet">
  <link href="http://vertx.io/stylesheets/font-awesome.min.css" media="screen" rel="stylesheet">
  <link href="http://vertx.io/javascripts/styles/rainbow.min.css" media="screen" rel="stylesheet">
  <!-- IE 6-8 support of HTML 5 elements -->
  <!--[if lt IE 9]>
  <script src="http://static.jboss.org/theme/js/libs/html5/pre3.6/html5.min.js"></script>
  <![endif]-->

  <link rel="apple-touch-icon" sizes="57x57" href="http://vertx.io/assets/favicons/vertx-favicon-7/apple-touch-icon-57x57.png">
  <link rel="apple-touch-icon" sizes="60x60" href="http://vertx.io/assets/favicons/vertx-favicon-7/apple-touch-icon-60x60.png">
  <link rel="apple-touch-icon" sizes="72x72" href="http://vertx.io/assets/favicons/vertx-favicon-7/apple-touch-icon-72x72.png">
  <link rel="apple-touch-icon" sizes="76x76" href="http://vertx.io/assets/favicons/vertx-favicon-7/apple-touch-icon-76x76.png">
  <link rel="apple-touch-icon" sizes="114x114" href="http://vertx.io/assets/favicons/vertx-favicon-7/apple-touch-icon-114x114.png">
  <link rel="apple-touch-icon" sizes="120x120" href="http://vertx.io/assets/favicons/vertx-favicon-7/apple-touch-icon-120x120.png">
  <link rel="apple-touch-icon" sizes="144x144" href="http://vertx.io/assets/favicons/vertx-favicon-7/apple-touch-icon-144x144.png">
  <link rel="apple-touch-icon" sizes="152x152" href="http://vertx.io/assets/favicons/vertx-favicon-7/apple-touch-icon-152x152.png">
  <link rel="apple-touch-icon" sizes="180x180" href="http://vertx.io/assets/favicons/vertx-favicon-7/apple-touch-icon-180x180.png">
  <link rel="icon" type="image/png" href="http://vertx.io/assets/favicons/vertx-favicon-7/favicon-32x32.png" sizes="32x32">
  <link rel="icon" type="image/png" href="http://vertx.io/assets/favicons/vertx-favicon-7/android-chrome-192x192.png" sizes="192x192">
  <link rel="icon" type="image/png" href="http://vertx.io/assets/favicons/vertx-favicon-7/favicon-96x96.png" sizes="96x96">
  <link rel="icon" type="image/png" href="http://vertx.io/assets/favicons/vertx-favicon-7/favicon-16x16.png" sizes="16x16">
  <link rel="manifest" href="http://vertx.io/assets/favicons/vertx-favicon-7/manifest.json">
  <link rel="mask-icon" href="http://vertx.io/assets/favicons/vertx-favicon-7/safari-pinned-tab.svg" color="#5bbad5">
  <meta name="msapplication-TileColor" content="#7d3194">
  <meta name="msapplication-TileImage" content="http://vertx.io/assets/favicons/vertx-favicon-7/mstile-144x144.png">
  <meta name="theme-color" content="#ffffff">

  <link href="http://fonts.googleapis.com/css?family=Ubuntu:400,500,700,400italic" rel="stylesheet" type="text/css">
  <link rel="alternate" type="application/rss+xml" title="RSS"
     href="http://vertx.io/feed.xml">
  <script>
    (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
      (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
      m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
    })(window,document,'script','//www.google-analytics.com/analytics.js','ga');
    ga('create', 'UA-30144458-1', 'auto');
    ga('create', 'UA-71153120-1', 'auto', 'tracker');
    ga('send', 'pageview');
    ga('tracker.send', 'pageview');
  </script>
</head>
<body>

<a href="http://www.reactivemanifesto.org/" id="reactive-manifesto-banner">
  <img style="border: 0; position: fixed; right: 0; top:0; z-index: 9000"
    src="http://d379ifj7s9wntv.cloudfront.net/reactivemanifesto/images/ribbons/we-are-reactive-black-right.png">
</a>

<a id="skippy" class="sr-only sr-only-focusable" href="#content"><div class="container"><span class="skiplink-text">Skip to main content</span></div></a>

<header class="navbar navbar-default navbar-static-top" id="top" role="banner">
  <div class="container">
    <div class="navbar-header">
      <button class="navbar-toggle collapsed" type="button" data-toggle="collapse" data-target="#vertx-navbar-collapse">
        <span class="sr-only">Toggle navigation</span>
        <span class="icon-bar"></span>
        <span class="icon-bar"></span>
        <span class="icon-bar"></span>
      </button>
      <a href="http://vertx.io/" class="navbar-brand"><img alt="Brand" src="http://vertx.io/assets/logo-sm.png"></a>
    </div>
    <nav class="collapse navbar-collapse" id="vertx-navbar-collapse">
      <ul class="nav navbar-nav navbar-right">
        <li><a href="http://vertx.io/download/">Download</a></li>
        <li><a href="http://vertx.io/docs/">Documentation</a></li>
        <li><a href="https://github.com/vert-x3/wiki/wiki">Wiki</a></li>
        <li><a href="http://vertx.io/community/">Community</a></li>
        <li><a href="http://vertx.io/materials/">Materials</a></li>
        <li><a href="http://vertx.io/blog/">Blog</a></li>        
      </ul>
    </nav>
  </div>
</header>



  <div class="page-header" id="content">
    <div class="container">
      <div class="row">
        <div class="col-sm-12">
          <h1>The Apache Shiro Auth provider implementation</h1>
          
        </div>
      </div>
    </div>
  </div>




<div id="content">
  <div class="container docs-content">
    <div class="row">
      <div class="col-sm-12 col-md-push-9 col-md-3 hidden-xs hidden-sm">
        <div id="sidebar" data-spy="affix">
          <ul class="sectlevel1">
<li><a href="#_the_apache_shiro_auth_provider_implementation">The Apache Shiro Auth provider implementation</a></li>
<li><a href="#_authentication">Authentication</a></li>
<li><a href="#_authorisation_permission_role_model">Authorisation - Permission-Role Model</a>
<ul class="sectlevel2">
<li><a href="#_the_shiro_properties_auth_provider">The Shiro properties auth provider</a></li>
<li><a href="#_the_shiro_ldap_auth_provider">The Shiro LDAP auth provider</a></li>
<li><a href="#_using_another_shiro_realm">Using another Shiro Realm</a></li>
</ul>
</li>
</ul>
        </div>
      </div>
      <div class="col-sm-12 col-md-pull-3 col-md-9">
        <div class="toc hidden-md hidden-lg">
          <h2>Table of Contents</h2>
          <ul class="sectlevel1">
<li><a href="#_the_apache_shiro_auth_provider_implementation">The Apache Shiro Auth provider implementation</a></li>
<li><a href="#_authentication">Authentication</a></li>
<li><a href="#_authorisation_permission_role_model">Authorisation - Permission-Role Model</a>
<ul class="sectlevel2">
<li><a href="#_the_shiro_properties_auth_provider">The Shiro properties auth provider</a></li>
<li><a href="#_the_shiro_ldap_auth_provider">The Shiro LDAP auth provider</a></li>
<li><a href="#_using_another_shiro_realm">Using another Shiro Realm</a></li>
</ul>
</li>
</ul>
        </div>
        <div class="sect1">
<h2 id="_the_apache_shiro_auth_provider_implementation">The Apache Shiro Auth provider implementation</h2>
<div class="sectionbody">
<div class="paragraph">
<p>This is an auth provider implementation that uses <a href="http://shiro.apache.org/">Apache Shiro</a>.</p>
</div>
<div class="paragraph">
<p>To use this
project, add the following dependency to the <em>dependencies</em> section of your build descriptor:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>Maven (in your <code>pom.xml</code>):</p>
</li>
</ul>
</div>
<div class="listingblock">
<div class="content">
<pre class="prettyprint highlight"><code class="language-xml" data-lang="xml">&lt;dependency&gt;
  &lt;groupId&gt;io.vertx&lt;/groupId&gt;
  &lt;artifactId&gt;vertx-auth-shiro&lt;/artifactId&gt;
  &lt;version&gt;3.3.3&lt;/version&gt;
&lt;/dependency&gt;</code></pre>
</div>
</div>
<div class="ulist">
<ul>
<li>
<p>Gradle (in your <code>build.gradle</code> file):</p>
</li>
</ul>
</div>
<div class="listingblock">
<div class="content">
<pre class="prettyprint highlight"><code class="language-groovy" data-lang="groovy">compile 'io.vertx:vertx-auth-shiro:3.3.3'</code></pre>
</div>
</div>
<div class="paragraph">
<p>We provide out of the box support for properties and LDAP based auth using Shiro, and you can also plugin in any
other Shiro Realm which expects username and password for credentials.</p>
</div>
<div class="paragraph">
<p>To create an instance of the provider you use <code><a href="../../jsdoc/module-vertx-auth-shiro-js_shiro_auth-ShiroAuth.html">ShiroAuth</a></code>. You specify the type of
Shiro auth provider that you want with <code><a href="../enums.html#ShiroAuthRealmType">ShiroAuthRealmType</a></code>, and you specify the
configuration in a JSON object.</p>
</div>
<div class="paragraph">
<p>Here&#8217;s an example of creating a Shiro auth provider by specifying the type:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="prettyprint highlight"><code class="language-java" data-lang="java">var ShiroAuth = require("vertx-auth-shiro-js/shiro_auth");

var config = {
  "properties_path" : "classpath:test-auth.properties"
};

var provider = ShiroAuth.create(vertx, 'PROPERTIES', config);</code></pre>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_authentication">Authentication</h2>
<div class="sectionbody">
<div class="paragraph">
<p>When authenticating using this implementation, it assumes <code>username</code> and <code>password</code> fields are present in the
authentication info:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="prettyprint highlight"><code class="language-java" data-lang="java">var authInfo = {
  "username" : "tim",
  "password" : "sausages"
};

authProvider.authenticate(authInfo, function (res, res_err) {
  if (res_err == null) {
    var user = res;
  } else {
    // Failed!
  }
});</code></pre>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_authorisation_permission_role_model">Authorisation - Permission-Role Model</h2>
<div class="sectionbody">
<div class="paragraph">
<p>Although Vert.x auth itself does not mandate any specific model of permissions (they are just opaque strings), this
implementation uses a familiar user/role/permission model, where a user can have zero or more roles and a role
can have zero or more permissions.</p>
</div>
<div class="paragraph">
<p>If validating if a user has a particular permission simply pass the permission into.
<code><a href="../../jsdoc/module-vertx-auth-common-js_user-User.html#isAuthorised">isAuthorised</a></code> as follows:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="prettyprint highlight"><code class="language-java" data-lang="java">user.isAuthorised("newsletter:edit:13", function (res, res_err) {
  if (res_err == null) {
    var hasPermission = res;
  } else {
    // Failed to
  }
});</code></pre>
</div>
</div>
<div class="paragraph">
<p>If validating that a user has a particular <em>role</em> then you should prefix the argument with the role prefix.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="prettyprint highlight"><code class="language-java" data-lang="java">user.isAuthorised("role:manager", function (res, res_err) {
  if (res_err == null) {
    var hasRole = res;
  } else {
    // Failed to
  }
});</code></pre>
</div>
</div>
<div class="paragraph">
<p>The default role prefix is <code>role:</code>. You can change this with <code><a href="../../jsdoc/module-vertx-auth-shiro-js_shiro_auth-ShiroAuth.html#setRolePrefix">setRolePrefix</a></code>.</p>
</div>
<div class="sect2">
<h3 id="_the_shiro_properties_auth_provider">The Shiro properties auth provider</h3>
<div class="paragraph">
<p>This auth provider implementation uses Apache Shiro to get user/role/permission information from a properties file.</p>
</div>
<div class="paragraph">
<p>Note that roles are not available directly on the API due to the fact that vertx-auth tries to be as portable as
possible. However one can run assertions on role by using the prefix <code>role:</code> or by specifying the prefered prefix
with <code><a href="../../jsdoc/module-vertx-auth-shiro-js_shiro_auth-ShiroAuth.html#setRolePrefix">setRolePrefix</a></code>.</p>
</div>
<div class="paragraph">
<p>The implementation will, by default, look for a file called <code>vertx-users.properties</code> on the classpath.</p>
</div>
<div class="paragraph">
<p>If you want to change this, you can use the <code>properties_path</code> configuration element to define how the properties
file is found.</p>
</div>
<div class="paragraph">
<p>The default value is <code>classpath:vertx-users.properties</code>.</p>
</div>
<div class="paragraph">
<p>If the value is prefixed with <code>classpath:</code> then the classpath will be searched for a properties file of that name.</p>
</div>
<div class="paragraph">
<p>If the value is prefixed with <code>file:</code> then it specifies a file on the file system.</p>
</div>
<div class="paragraph">
<p>If the value is prefixed with <code>url:</code> then it specifies a URL from where to load the properties.</p>
</div>
<div class="paragraph">
<p>The properties file should have the following structure:</p>
</div>
<div class="paragraph">
<p>Each line should either contain the username, password and roles for a user or the permissions in a role.</p>
</div>
<div class="paragraph">
<p>For a user line it should be of the form:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>user.{username}={password},{roleName1},{roleName2},...,{roleNameN}</pre>
</div>
</div>
<div class="paragraph">
<p>For a role line it should be of the form:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>role.{roleName}={permissionName1},{permissionName2},...,{permissionNameN}</pre>
</div>
</div>
<div class="paragraph">
<p>Here&#8217;s an example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre>user.tim = mypassword,administrator,developer
user.bob = hispassword,developer
user.joe = anotherpassword,manager
role.administrator=*
role.manager=play_golf,say_buzzwords
role.developer=do_actual_work</pre>
</div>
</div>
<div class="paragraph">
<p>When describing roles a wildcard <code>*</code> can be used to indicate that the role has all permissions.</p>
</div>
</div>
<div class="sect2">
<h3 id="_the_shiro_ldap_auth_provider">The Shiro LDAP auth provider</h3>
<div class="paragraph">
<p>The LDAP auth realm gets user/role/permission information from an LDAP server.</p>
</div>
<div class="paragraph">
<p>The following configuration properties are used to configure the LDAP realm:</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1"><code>ldap-user-dn-template</code></dt>
<dd>
<p>this is used to determine the actual lookup to use when looking up a user with a particular
id. An example is <code>uid={0},ou=users,dc=foo,dc=com</code> - the element <code>{0}</code> is substituted with the user id to create the
actual lookup. This setting is mandatory.</p>
</dd>
<dt class="hdlist1"><code>ldap_url</code></dt>
<dd>
<p>the url to the LDAP server. The url must start with <code>ldap://</code> and a port must be specified.
An example is <code>ldap://myldapserver.mycompany.com:10389</code></p>
</dd>
<dt class="hdlist1"><code>ldap-authentication-mechanism</code></dt>
<dd>
<p>TODO</p>
</dd>
<dt class="hdlist1"><code>ldap-context-factory-class-name</code></dt>
<dd>
<p>TODO</p>
</dd>
<dt class="hdlist1"><code>ldap-pooling-enabled</code></dt>
<dd>
<p>TODO</p>
</dd>
<dt class="hdlist1"><code>ldap-referral</code></dt>
<dd>
<p>TODO</p>
</dd>
<dt class="hdlist1"><code>ldap-system-username</code></dt>
<dd>
<p>TODO</p>
</dd>
<dt class="hdlist1"><code>ldap-system-password</code></dt>
<dd>
<p>TODO</p>
</dd>
</dl>
</div>
</div>
<div class="sect2">
<h3 id="_using_another_shiro_realm">Using another Shiro Realm</h3>
<div class="paragraph">
<p>It&#8217;s also possible to create an auth provider instance using a pre-created Apache Shiro Realm object.</p>
</div>
<div class="paragraph">
<p>This is done as follows:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="prettyprint highlight"><code class="language-java" data-lang="java">var ShiroAuth = require("vertx-auth-shiro-js/shiro_auth");

var provider = ShiroAuth.create(vertx, realm);</code></pre>
</div>
</div>
<div class="paragraph">
<p>The implementation currently assumes that user/password based authentication is used.
&lt;a href="mailto:julien@julienviet.com"&gt;Julien Viet&lt;/a&gt;&lt;a href="http://tfox.org"&gt;Tim Fox&lt;/a&gt;</p>
</div>
</div>
</div>
</div>

        

        
          <div id="footer">
            <div id="footer-text">
              
                Last updated 2016-09-12 08:38:04 CEST
              
              
            </div>
          </div>
        
      </div>
    </div>
  </div>
</div>

<footer>
  <div class="container">
    <div class="row">
      <div class="col-xs-6 col-sm-3 col-md-3 col-lg-2">
        <h2>Vert.x</h2>
        <ul class="list-unstyled">
          <li><a href="http://vertx.io/">Home</a></li>
          <li><a href="http://vertx.io/download/">Download</a></li>
          <li><a href="http://vertx.io/docs/">Documentation</a></li>
          <li><a href="https://github.com/vert-x3/wiki/wiki">Wiki</a></li>
          <li><a href="http://vertx.io/blog/">Blog</a></li>
          <li><a href="http://vertx.io/vertx2/" class="vertx-2-link">Vert.x 2</a></li>
        </ul>
      </div>
      <div class="col-xs-6 col-sm-3 col-md-3 col-lg-2">
        <h2>Community</h2>
        <ul class="list-unstyled">
          <li><a href="http://vertx.io/community/">Help &amp; Contributors</a></li>
          <li><a href="http://vertx.io/materials/">Learning materials</a></li>
          <li><a href="https://groups.google.com/forum/?fromgroups#!forum/vertx">User Group</a></li>
          <li><a href="https://groups.google.com/forum/?fromgroups#!forum/vertx-dev">Developer Group</a></li>
        </ul>
      </div>

      <div class="col-xs-12 col-sm-6 col-lg-offset-2 col-md-6 copyright">
        <p>Vert.x is open source and dual licensed under the <a href="https://www.eclipse.org/org/documents/epl-v10.php">Eclipse Public License 1.0</a> and <a href="https://www.apache.org/licenses/LICENSE-2.0.html">Apache License 2.0</a>.</p>
        <p>This website is licensed under the <a href="http://creativecommons.org/licenses/by-sa/3.0/">CC BY-SA 3.0 License</a>.<br>
        Design by <a href="http://www.michel-kraemer.com">Michel Kr&auml;mer</a>. <a href="http://www.entypo.com">Entypo pictograms</a> by Daniel Bruce.</p>
        <div class="row">
          <div class="col-xs-12 col-lg-offset-1 col-md-5">
            <a href="http://eclipse.org">
            <img class="logo eclipse-logo" src="http://vertx.io/assets/eclipse_logo_grey_small.png" width="204" height="48">
            </a>
          </div>
          <div class="col-xs-12 col-md-offset-2 col-lg-offset-0 col-md-5">
            <a href="http://cloudbees.com">
            <img class="logo cloudbees-logo" src="http://vertx.io/assets/Button-Built-on-CB-1-grey.png" width="180" height="48">
           </a>
          </div>
          <div class="col-xs-12 col-md-offset-2 col-lg-offset-1 col-md-5 jprofiler">
            <a href="http://www.ej-technologies.com/products/jprofiler/overview.html"
            style="text-decoration:none">
            <img class="logo jprofiler-logo" src="http://vertx.io/assets/jprofiler-logo.png" width="48" height="48"><span class="jprofiler-logo">&nbsp; JPROFILER</span>
            </a>
          </div>
        </div>
      </div>
    </div>
  </div>
</footer>

<script src="http://static.jboss.org/theme/js/libs/jquery/jquery-1.9.1.min.js"></script>
<script src="http://vertx.io/javascripts/bootstrap.min.js"></script>
<script src="http://vertx.io/javascripts/highlight.pack.js"></script>
<script>hljs.initHighlightingOnLoad();</script>



<script src="http://vertx.io/javascripts/sidebar.js"></script>


</body>
</html>
